Obtain the Hash of the Document in Accordance with a Signature Definition

Alias

DocumentSignerToBeSignedCalculation

Description

Obtains the hash of a document according to a signature definition and modifies it with the information on the hash (the to_be_signed property). Optionally, the parameters in the signature definition can be modified before obtaining the hash. Currently, only the following modifications can be performed:

  • Provide (or substitute) the signer's certificate, leaving all the other parameters that the signature already has, i.e., provide the value of the parameters.certificate property of the signature definition.

  • Provide the parameters of the signature definition, completely replacing (where appropriate) the already defined parameters, i.e., provide the value of the parameters property of the signature definition.

Important

After obtaining the hash of a document from a signature definition, this definition can only be updated to provide it the digital signature that corresponds to the hash obtained. If a document and signature definitions resource contains several signature definitions, between the obtaining of the hash and the update that provides the digital signature to signature definition, the obtaining of the hash and the update that provides the digital signature cannot be performed for a different signature definition.

Behavior for When Parameters Are Missing from the Signature Definition

Although it is possible to create a signature definition without the parameters property, this property is required for calculating the hash of the data to be signed. Thus, if the signature definition lacks the parameters property when this operation is executed, it should be provided in the request body.

We distinguish between when the signature definition is for a PAdES signature from when it is for an XMLDSig/XAdES signature.

Missing Parameters in the Definition of a PAdES Signature

When this operation is executed on a signature definition applied to a PDF document, the data structures required for containing the information on this signature (principally, the signature dictionary) is created in the PDF document (and are initialized). If at this time the signature definition is missing any parameters properties, the structures are informed as set out for an ETSI PAdES-Basic signature (ETSI TS 102 778-2) that has no appearance and for which the SHA-256 algorithm is used to obtain it. These structures are also informed that the signature is an ordinary one (not a certification signature), and 12,228 bytes is reserved (in the signature dictionary) for inserting the electronic signature itself.

If, however, the signature definition contains parameters (i.e., it has the parameters property), the data structures of the PDF are informed without taking into account the optional parameters not present, except in the following cases:

  • If the estimated_signature_size property is not present, the value 12,288 is taken by default.

  • If the certification_level property is not present, the value 0 is taken by default. As a result, the signature is ordinary (not a certification signature).

  • If the appearance.signature_details property is present but the appearance.signature_details.font.style property is not, the value "normal" is taken by default. As a result, the font style used in the signature appearance will be normal.

  • If the appearance.signature_details property is present but the appearance.signature_details.font.color property is not, the value {r=0; g=0; b=0} is taken by default. As a result, the color of the font used in the signature appearance will be black.

  • If the appearance.signature_details property is present but the appearance.signature_details.font.encoding property is not, the value "latin1" is taken by default. As a result, the code of the characters used in the signature appearance will be ISO-8859-1 (Latin 1).

  • If the appearance.signature_details property is present but the appearance.signature_details.font.embed property is not, the value true is taken by default. As a result, the font used in the signature appearance will be included in the PDF document.

  • If the appearance.signature_details is present, one of the elements of the appearance.signature_details.details[] array is of the date type and the signature definition does not specify the timezone property for this element, the timezone of the TRIDENT platform is taken by default.

  • If the appearance.signature_details is present, one of the elements of the appearance.signature_details.details[] array is of the date type and the signature definition does not specify the format property for this element, the "yyyy.MM.dd hh:mm:ss XXX" value is taken by default.

Missing Parameters in the Definition of an XMLDSig/XAdES Signature

When this operation is executed on a signature definition for an XMLDSig/XAdES signature, whether certain parameters properties are required and the default values any optional properties take depend on the position of the signature with respect to the signed data specified by the required signature_target.signature_packaging property.

  • If the signature definition is for a detached signature and only the type property (which is required) is present, an externally detached signature is generated on the document (of any type) to which the signature definition is applied. The signature is applied to a different document and will reference the signed document with a URL with the "file:///<docname>" format, where <docname> is the name of the document in question.

  • If the signature definition corresponds to an enveloped signature and only the type property (which is required) is present, a signature is generated on the XML document to which the signature definition is applied, and the signature is added to this document as the last child node of the root node.

  • If the signature definition is for a enveloping signature, an enveloping XML signature is generated that contains the signed document encoded in base64.

Request

PUT /trustedx-resources/esignsp/v2/documents/{doc_and_sigdefs_id}/signers/{signature_definition_id}/to_be_signed

Parameters

Name

Type

Usage

Description

doc_and_sigdefs_id

path

Required

Identifier of the document and signature definitions resource that contains the signature definition applied to obtain the hash.

signature_definition_id

path

Required

Identifier of the signature definition applied to obtain the hash.

Authorization

The request must contain a bearer access token generated by an authorization server of the platform. This token must have a scope that includes the urn:safelayer:eidas:sign:process:document value and must be used as explained in RFC 6750. Basically, the access token must be included in an Authorization header as follows:

Authorization: Bearer <token>

The client application must obtain the required access token via a client credentials grant OAuth 2.0 interaction with the platform.

Content-Type Header

For the case of modifying the signature definition to be applied (e.g., to send the signer's certificate) before the hash is obtained, the request must include the following Content-Type header:

Content-Type: application/json

Body

For the case of modifying the signature definition to be applied (e.g., to send the signer's certificate), the body of the request must include the following JSON object:

{
"parameters" : {Parameters}
}

Property

Usage

Description

parameters

Required if the request has a body.

Characteristics for extending or changing what is established by the signature policy of the signature definition.

Response

Status-Line

Value

Description

HTTP/1.1 200 OK

The calculation of the hash was performed correctly and its data is in the body of the response.

HTTP/1.1 409 Conflict

An attempt was made to obtain the hash using a signature definition that had already been used for obtaining the hash of the document to which it will be applied. I.e., an attempt was made to obtain the same hash a second time.

Others

See HTTP Response Status for all the possible cases.

Content-Type Header

Content-Type: application/json

Body

If the hash is successfully calculated, the body contains the following JSON object:

{
"type" : "x509",
"digest_algorithm" : {string},
"digest_value" : {string}
}

Property

Description

type

Always has the "x509" value.

digest_algorithm

Hash algorithm. The value of this property can be sha1, sha256, sha384 or sha512.

digest_value

Hash of the document and the attributes signed according to the signature definition.